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Basic and Introductory Concepts 

Palette 

typedef struct RGB { 

byter; 

byteg; 

byteb; 
}RGB; 

Palette entries consist of three bytes - one byte each of value for Red, Green, 
and Blue. Unlike many PC VGA cards which only use 6 bits of each color vector, 
the Second Sight supports a full palette range of 16.7M colors; i.e., each R G or 
B value is 256 levels. 

Palette data is required in Second Sight's 256 color modes, as well as in its text 
modes (which only use the first 16 palette entries). The HIghColor and 
TrueColor modes of the card do not use palettes, because they directly store 
RGB color information in each pixel. 



Image and Pixel Buffers 

typedef struct LocInfo2 ( 
Word portSCB; 
union { 

struct ( 

Pointer ptrToPixImage; 
Word width; 
Rect BoundsRect ; 
) lil; 
struct { 

Byte flags; 
Pointer ptrToPixImage; 
Word width; 
Byte pixDepth; 
Rect BoundsRect; 
) li2; 
} info; 
); 



/* $5A5A to indicate a Loclnfo2 record */ 



/* these fields are the same as the 7 
/* the regular Loclnfo record 7 



/* 1 = VGA buffer, = GS Mem buffer 7 
/* offset in VGA memory, or IIGS address 7 
/* width of pixel map in pixels 7 
/* number of bits per pixel 7 



The Loclnfo2 record is a backwards-compatible extension of the original 
QuickDraw Locinfo record. It specifies the information necessary to locate the 
memory address and mask of an arbitrary pixel in a pixel map, either in VGA 
memory or GS memory. The equation to locate the address of a pixel, assuming 
a pixei depth of 8, 16, or 24 bits, is: 

address = (Y * width) + (X * (pixDepth / 8) ) + ptrToPixImage; 



Library Routines 

The library routines described below are implemented as a C-accessible 
library. They should be accessible from any language that can operate with the 
ORCA™ development system. 

The actual implementation of the routines is undefined. Currently it is a simple 
library, but in the future the core routines may be implemented as an IPC 
process (which would provide the most flexible and quickest method of 
accessing these routines such that the code is shared - a necessity in 
multitasking systems). 



int vgaStartup (void) 

Returns -1 if no Second Sight card is found, or if the Second Sight library 
is not found via IPC. 

Returns if the card is found, and the library is properly initialized 

vgaStartup does a number of things. First, It checks to see if a Second Sight 
card is installed in the computer. If no card is found, an error is returned. 

Second, the routine tries to locate the core Second Sight library; this is 
generally an INIT file which contains IPC "hooks", if this code is not found, an 
error is returned. 

This call must be made before any other calls in this document. 



int vgaLastError (void) 

Returns the last error code found by the VGA library. See the section on each 
library call for a list of possible errors. 



int vgaCopYPixelMap(int x,int y,LocInfo2 *loc,Rect *mapRect} 

x,y X & y coordinate on VGA screen to place pixelmap 

ioc pointer to a Loclnfo2 record specifying the attributes of the 

source pixel map. 
mapRect pointer to a Rect structure describing the portion of the 

source pixelmap to copy. 

This function copies a portion of a color pixelmap (the pixel depth is specified in 
the Loclnfo2 record) to the VGA display. No clipping is performed other than 
insuring that no data is copied outside of the VGA memory specified by the 
global VGA Loclnfol! record. 



The pixel depths of the two bitmaps must be the same, and pixels may oniy be 
copied on at least a one-byte boundary. See the function vgaPixelMapToPort 
for a function which will color-expand 



int vgaSetMasterLocInfo(LocInfo2 *loc) 

This function sets the master VGA Loclnfo record. This record defines the 
characteristics of the video display, such as height, width, pixel depth, etc. 



int vgaSetMode ( int vgaMode , int shadowFlag } 

vgaMode A VGA Mode number. See the Table below for details. 

shadowFlag Controls the Second Sight's automatic shadowing of Apple 

II video modes. True (1) turns shadowing off, False (0) turns 
shadowing back on. If an application is going to draw 
directly to the screen, it must turn shadowing off. 

Possible Errors: 

vgalNVALID_MODE_NUM 0x01 

An invalid video mode number was passed to vgaSetMode. 
The mode number given does not correspond to any 
supported video mode. 

vgaUNSUPPORTED_MODE 0x02 

The specified video mode is not supported by the monitor 
currently attached to the Second Sight. This could also 
mean that a > 256 color mode was selected, but the DAG is 
not capable of High Color or True Color. 



int vgaSetPalette{RGB palette[], int startind, int nuiriEntries) 

Sets numEntries entries of palette data, starting at entry startind on the Second 
Sight card to the values specified in the pointer palette. 



int vgaSetPaletteEntrY(RGB *palEntry, int color Ind) 

Sets a single palette entry specified by color ind to the RGB values stored at the 
paiEntry pointer. 



int vgaLockPaletteRange (int startind, int endind, word userlD) 
int vgaUnlockPaletteRange (int startind, int endind, word userlD! 
int vgaFindAndLockPaletteRange (int numEntries) 



Allocates a range of palette entries for the exclusive use of the calling 
application. This allows an application to set aside a certain number of colors 
for its own use, assured that its use of that entry won't Interfere with other 
applications' colors or vice-versa. 



int vgaMapColor (RGB *color) ; 

Looks through the existing palette for the closest match to the specified color, 
and returns the index of that color. This routine may not return an index to a 
color anything at al! like the specified one. If an application does not lock its 
colors, it may want to periodically redraw its windows after remapping colors 

with vgaMapColor. 



int vgaUploadVideoData(void *dest_adr, LongWord size, void *gs_adr} 

Similar to the „UpioadData function in the low level library. However, 
vgaUploadVideoData only transfers data to video memory. Further, it knows 
how to deal with the 512K boundary. Use this function to seamlessly transfer 
data from the GS to video memory without worrying about splitting up your 
transfers - this routine does it for you. 

dest_adr is of course the destination offset In VGA video memory, size is the 
number of bytes to transfer, and gs_adr is the address in GS memory of the 
beginning of the block to transfer. 



File Formats 

We highly recommend that only _one_ set of routines to read/write this file 
format be created: modules for Seven Hills' "Babelfish" product. 

The requirements for an image file format for Second Sight are as follows: 

Must be able to handle images of varying pixel depths 

• Should be somewhat compatible with existing software, to provide 
a "bridge" for users who do not yet have Second Sight. 

• Should be quick to load and save. 

To this end, we have chosen an extension to the APF (Apple Referred Format). 
We have defined three new chunk types, "SVGA" to denote an 8bpp (or higher) 
image, "SVGC" to denote a PackBytes-com pressed 8bpp image, and "SVGP", 
to denote an 8bpp palette. 

SVGA 

Word pixDepth ; /* number of bits per pixel in this image V 

Word widthPixels; /* number of pixels wide this image is 7 

Word heightpixels; /* number of pixels tall this image is 7 

byte image [ widthPixels *heightPixels* (pixDepth/ 8) ] ; 

/* 

SVGC 

Word pixDepth ; /* number of bits per pixel in this image - always 87 

Word widthPixels; /* number of pixels wide this image is 7 

Word heightpixels; /* number of pixels tall this Image is 7 

. . scanline data . . /* each scanline In turn, run through PackBytes 7 

SVGP 

Word numEntries ; /* number of palette entries 7 

RGB palette [numEntries] ; /* palette data In the form of RGB' Struct 7 

To aid in compatibility of new pictures with existing applications, a grayscale 
version of the VGA image should be stored in the standard MAIN and PALETTE 
chunks of the file. Grayscale was chosen because of ease of conversion of any 
format picture to grayscale in 16-colors; if the application wishes to do a 
complicated quantization technique to choose colors for this "compatibility" 
image, it may do so, but this is not required. 

Compression is-not specified for-ISbpp and24bpp images, because the only 
decent existing standard for compression of TrueColor and HighColor Images is 
JPEG - an algorithm that is extremely time-consuming to execute on a IIGS. 
However, we expect that JPEG will come into more common use on the IIGS 
due to SecondSight's TrueCoior and HighColor capabilities. 



Text Mode 



#Cobrs 



A' 



ModeNunfel 



Apple RGB Compatible? 



40X25 

80x25 

80x43 

80x50 

80x60 

132x25 

132x43 

132x60 



560x192 

280x192 

40x24 

80x24 

640x200 



16 
16 
16 
16 
16 
16 
16 
16 



Graphics Mode #Cobrs 



0(320x200 256 

— 320x200 32K 
320x200 1 6M 

c<'640x400 256 

-^640x400 32K 

640x400 16M 

640x480 256 

— 640x480 32K 
640x480 16M 
800x600 256 
800x600 32K 
1024x768 256 - 

Emulation Mode # Cobrs 



16 
16 
16 
16 
256 



$01 
$03 



$50 
$51 
$4F 

Mode Number 



$13 
$70 

$61 
$5B 



$5A 
$5F 



$60 
$59 

Mode Number 



$FA 
$FB 
$FC 
$FD 
$FE 



Yes 

Yes 

No 

No 

No 

Yes 

No 

No 



Yes 
Yes 



Yes (interiace) 
Yes (interlace) 

No 
No 
No 
No 
No 
No 



Yes 
Yes 
Yes 
Yes 

Yes 



x256 256 colors using a 256 entry palette 

x32K 65536 direct colors, using 6 bits for Green, and 5 each for Red and 

Blue, _or_ 32768 colors direct using 5 bits each for R, G, B. 
x16M 16.7Mi!lion direct colors, using 8 bits each for Red, Green, and Blue 



This list is notto be construed as a list of video modes that any particular 
application or any particular version of the C VGA library suports. 



